<!DOCTYPE html>
<html lang="en-US">
<head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta name="language" content="en" />
        <link href="./assets/ffd55088/css/bootstrap.css" rel="stylesheet">
<link href="./assets/5cf9384a/solarized_light.css" rel="stylesheet">
<link href="./assets/6c54116e/style.css" rel="stylesheet">
<script src="./assets/a44cef0f/jquery.js"></script>
<script src="./assets/ffd55088/js/bootstrap.js"></script>
<script src="./assets/8ac4e28a/jssearch.js"></script>    <title>Configurations - Key Concepts - The Definitive Guide to Yii 2.0</title>
</head>
<body>

<div class="wrap">
    <nav id="w339" class="navbar-inverse navbar-fixed-top navbar" role="navigation"><div class="navbar-header"><button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#w339-collapse"><span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span></button><a class="navbar-brand" href="./index.html">The Definitive Guide to Yii 2.0</a></div><div id="w339-collapse" class="collapse navbar-collapse"><ul id="w340" class="navbar-nav nav"><li><a href="./index.html">Class reference</a></li>
<li class="dropdown"><a class="dropdown-toggle" href="#" data-toggle="dropdown">Extensions <b class="caret"></b></a><ul id="w341" class="dropdown-menu"><li><a href="./ext-apidoc-index.html" tabindex="-1">apidoc</a></li>
<li><a href="./ext-authclient-index.html" tabindex="-1">authclient</a></li>
<li><a href="./ext-bootstrap-index.html" tabindex="-1">bootstrap</a></li>
<li><a href="./ext-codeception-index.html" tabindex="-1">codeception</a></li>
<li><a href="./ext-debug-index.html" tabindex="-1">debug</a></li>
<li><a href="./ext-elasticsearch-index.html" tabindex="-1">elasticsearch</a></li>
<li><a href="./ext-faker-index.html" tabindex="-1">faker</a></li>
<li><a href="./ext-gii-index.html" tabindex="-1">gii</a></li>
<li><a href="./ext-imagine-index.html" tabindex="-1">imagine</a></li>
<li><a href="./ext-jui-index.html" tabindex="-1">jui</a></li>
<li><a href="./ext-mongodb-index.html" tabindex="-1">mongodb</a></li>
<li><a href="./ext-redis-index.html" tabindex="-1">redis</a></li>
<li><a href="./ext-smarty-index.html" tabindex="-1">smarty</a></li>
<li><a href="./ext-sphinx-index.html" tabindex="-1">sphinx</a></li>
<li><a href="./ext-swiftmailer-index.html" tabindex="-1">swiftmailer</a></li>
<li><a href="./ext-twig-index.html" tabindex="-1">twig</a></li></ul></li>
<li><a href="./guide-README.html">Guide</a></li></ul><div class="navbar-form navbar-left" role="search">
  <div class="form-group">
    <input id="searchbox" type="text" class="form-control" placeholder="Search">
  </div>
</div>
</div></nav>
    <div id="search-resultbox" style="display: none;" class="modal-content">
        <ul id="search-results">
        </ul>
    </div>

    
<div class="row">
    <div class="col-md-2">
                <div id="navigation" class="list-group"><a class="list-group-item" href="#navigation-323" data-toggle="collapse" data-parent="#navigation">Introduction <b class="caret"></b></a><div id="navigation-323" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-intro-yii.html">About Yii</a>
<a class="list-group-item" href="./guide-intro-upgrade-from-v1.html">Upgrading from Version 1.1</a></div>
<a class="list-group-item" href="#navigation-324" data-toggle="collapse" data-parent="#navigation">Getting Started <b class="caret"></b></a><div id="navigation-324" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-start-installation.html">Installing Yii</a>
<a class="list-group-item" href="./guide-start-workflow.html">Running Applications</a>
<a class="list-group-item" href="./guide-start-hello.html">Saying Hello</a>
<a class="list-group-item" href="./guide-start-forms.html">Working with Forms</a>
<a class="list-group-item" href="./guide-start-databases.html">Working with Databases</a>
<a class="list-group-item" href="./guide-start-gii.html">Generating Code with Gii</a>
<a class="list-group-item" href="./guide-start-looking-ahead.html">Looking Ahead</a></div>
<a class="list-group-item" href="#navigation-325" data-toggle="collapse" data-parent="#navigation">Application Structure <b class="caret"></b></a><div id="navigation-325" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-structure-overview.html">Overview</a>
<a class="list-group-item" href="./guide-structure-entry-scripts.html">Entry Scripts</a>
<a class="list-group-item" href="./guide-structure-applications.html">Applications</a>
<a class="list-group-item" href="./guide-structure-application-components.html">Application Components</a>
<a class="list-group-item" href="./guide-structure-controllers.html">Controllers</a>
<a class="list-group-item" href="./guide-structure-models.html">Models</a>
<a class="list-group-item" href="./guide-structure-views.html">Views</a>
<a class="list-group-item" href="./guide-structure-modules.html">Modules</a>
<a class="list-group-item" href="./guide-structure-filters.html">Filters</a>
<a class="list-group-item" href="./guide-structure-widgets.html">Widgets</a>
<a class="list-group-item" href="./guide-structure-assets.html">Assets</a>
<a class="list-group-item" href="./guide-structure-extensions.html">Extensions</a></div>
<a class="list-group-item" href="#navigation-326" data-toggle="collapse" data-parent="#navigation">Handling Requests <b class="caret"></b></a><div id="navigation-326" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-runtime-overview.html">Overview</a>
<a class="list-group-item" href="./guide-runtime-bootstrapping.html">Bootstrapping</a>
<a class="list-group-item" href="./guide-runtime-routing.html">Routing and URL Creation</a>
<a class="list-group-item" href="./guide-runtime-requests.html">Requests</a>
<a class="list-group-item" href="./guide-runtime-responses.html">Responses</a>
<a class="list-group-item" href="./guide-runtime-sessions-cookies.html">Sessions and Cookies</a>
<a class="list-group-item" href="./guide-runtime-handling-errors.html">Handling Errors</a>
<a class="list-group-item" href="./guide-runtime-logging.html">Logging</a></div>
<a class="list-group-item active" href="#navigation-327" data-toggle="collapse" data-parent="#navigation">Key Concepts <b class="caret"></b></a><div id="navigation-327" class="submenu panel-collapse collapse in"><a class="list-group-item" href="./guide-concept-components.html">Components</a>
<a class="list-group-item" href="./guide-concept-properties.html">Properties</a>
<a class="list-group-item" href="./guide-concept-events.html">Events</a>
<a class="list-group-item" href="./guide-concept-behaviors.html">Behaviors</a>
<a class="list-group-item active" href="./guide-concept-configurations.html">Configurations</a>
<a class="list-group-item" href="./guide-concept-aliases.html">Aliases</a>
<a class="list-group-item" href="./guide-concept-autoloading.html">Class Autoloading</a>
<a class="list-group-item" href="./guide-concept-service-locator.html">Service Locator</a>
<a class="list-group-item" href="./guide-concept-di-container.html">Dependency Injection Container</a></div>
<a class="list-group-item" href="#navigation-328" data-toggle="collapse" data-parent="#navigation">Working with Databases <b class="caret"></b></a><div id="navigation-328" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-db-dao.html">Data Access Objects</a>
<a class="list-group-item" href="./guide-db-query-builder.html">Query Builder</a>
<a class="list-group-item" href="./guide-db-active-record.html">Active Record</a>
<a class="list-group-item" href="./guide-db-migrations.html">Migrations</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-sphinx/blob/master/docs/guide/README.md">Sphinx</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-redis/blob/master/docs/guide/README.md">Redis</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-mongodb/blob/master/docs/guide/README.md">MongoDB</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-elasticsearch/blob/master/docs/guide/README.md">ElasticSearch</a></div>
<a class="list-group-item" href="#navigation-329" data-toggle="collapse" data-parent="#navigation">Getting Data from Users <b class="caret"></b></a><div id="navigation-329" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-input-forms.html">Creating Forms</a>
<a class="list-group-item" href="./guide-input-validation.html">Validating Input</a>
<a class="list-group-item" href="./guide-input-file-upload.html">Uploading Files</a>
<a class="list-group-item" href="./guide-input-tabular-input.html">Collecting Tabular Input</a>
<a class="list-group-item" href="./guide-input-multiple-models.html">Getting Data for Multiple Models</a></div>
<a class="list-group-item" href="#navigation-330" data-toggle="collapse" data-parent="#navigation">Displaying Data <b class="caret"></b></a><div id="navigation-330" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-output-formatting.html">Data Formatting</a>
<a class="list-group-item" href="./guide-output-pagination.html">Pagination</a>
<a class="list-group-item" href="./guide-output-sorting.html">Sorting</a>
<a class="list-group-item" href="./guide-output-data-providers.html">Data Providers</a>
<a class="list-group-item" href="./guide-output-data-widgets.html">Data Widgets</a>
<a class="list-group-item" href="./guide-output-client-scripts.html">Working with Client Scripts</a>
<a class="list-group-item" href="./guide-output-theming.html">Theming</a></div>
<a class="list-group-item" href="#navigation-331" data-toggle="collapse" data-parent="#navigation">Security <b class="caret"></b></a><div id="navigation-331" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-security-overview.html">Overview</a>
<a class="list-group-item" href="./guide-security-authentication.html">Authentication</a>
<a class="list-group-item" href="./guide-security-authorization.html">Authorization</a>
<a class="list-group-item" href="./guide-security-passwords.html">Working with Passwords</a>
<a class="list-group-item" href="./guide-security-cryptography.html">Cryptography</a>
<a class="list-group-item" href="./guide-structure-views.html#security">Views security</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-authclient/blob/master/docs/guide/README.md">Auth Clients</a>
<a class="list-group-item" href="./guide-security-best-practices.html">Best Practices</a></div>
<a class="list-group-item" href="#navigation-332" data-toggle="collapse" data-parent="#navigation">Caching <b class="caret"></b></a><div id="navigation-332" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-caching-overview.html">Overview</a>
<a class="list-group-item" href="./guide-caching-data.html">Data Caching</a>
<a class="list-group-item" href="./guide-caching-fragment.html">Fragment Caching</a>
<a class="list-group-item" href="./guide-caching-page.html">Page Caching</a>
<a class="list-group-item" href="./guide-caching-http.html">HTTP Caching</a></div>
<a class="list-group-item" href="#navigation-333" data-toggle="collapse" data-parent="#navigation">RESTful Web Services <b class="caret"></b></a><div id="navigation-333" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-rest-quick-start.html">Quick Start</a>
<a class="list-group-item" href="./guide-rest-resources.html">Resources</a>
<a class="list-group-item" href="./guide-rest-controllers.html">Controllers</a>
<a class="list-group-item" href="./guide-rest-routing.html">Routing</a>
<a class="list-group-item" href="./guide-rest-response-formatting.html">Response Formatting</a>
<a class="list-group-item" href="./guide-rest-authentication.html">Authentication</a>
<a class="list-group-item" href="./guide-rest-rate-limiting.html">Rate Limiting</a>
<a class="list-group-item" href="./guide-rest-versioning.html">Versioning</a>
<a class="list-group-item" href="./guide-rest-error-handling.html">Error Handling</a></div>
<a class="list-group-item" href="#navigation-334" data-toggle="collapse" data-parent="#navigation">Development Tools <b class="caret"></b></a><div id="navigation-334" class="submenu panel-collapse collapse"><a class="list-group-item" href="https://github.com/yiisoft/yii2-debug/blob/master/docs/guide/README.md">Debug Toolbar and Debugger</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-gii/blob/master/docs/guide/README.md">Generating Code using Gii</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-apidoc">Generating API Documentation</a></div>
<a class="list-group-item" href="#navigation-335" data-toggle="collapse" data-parent="#navigation">Testing <b class="caret"></b></a><div id="navigation-335" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-test-overview.html">Overview</a>
<a class="list-group-item" href="./guide-test-environment-setup.html">Testing environment setup</a>
<a class="list-group-item" href="./guide-test-unit.html">Unit Tests</a>
<a class="list-group-item" href="./guide-test-functional.html">Functional Tests</a>
<a class="list-group-item" href="./guide-test-acceptance.html">Acceptance Tests</a>
<a class="list-group-item" href="./guide-test-fixtures.html">Fixtures</a></div>
<a class="list-group-item" href="#navigation-336" data-toggle="collapse" data-parent="#navigation">Special Topics <b class="caret"></b></a><div id="navigation-336" class="submenu panel-collapse collapse"><a class="list-group-item" href="https://github.com/yiisoft/yii2-app-advanced/blob/master/docs/guide/README.md">Advanced Project Template</a>
<a class="list-group-item" href="./guide-tutorial-start-from-scratch.html">Building Application from Scratch</a>
<a class="list-group-item" href="./guide-tutorial-console.html">Console Commands</a>
<a class="list-group-item" href="./guide-tutorial-core-validators.html">Core Validators</a>
<a class="list-group-item" href="./guide-tutorial-i18n.html">Internationalization</a>
<a class="list-group-item" href="./guide-tutorial-mailing.html">Mailing</a>
<a class="list-group-item" href="./guide-tutorial-performance-tuning.html">Performance Tuning</a>
<a class="list-group-item" href="./guide-tutorial-shared-hosting.html">Shared Hosting Environment</a>
<a class="list-group-item" href="./guide-tutorial-template-engines.html">Template Engines</a>
<a class="list-group-item" href="./guide-tutorial-yii-integration.html">Working with Third-Party Code</a></div>
<a class="list-group-item" href="#navigation-337" data-toggle="collapse" data-parent="#navigation">Widgets <b class="caret"></b></a><div id="navigation-337" class="submenu panel-collapse collapse"><a class="list-group-item" href="https://github.com/yiisoft/yii2-bootstrap/blob/master/docs/guide/README.md">Bootstrap Widgets</a>
<a class="list-group-item" href="https://github.com/yiisoft/yii2-jui/blob/master/docs/guide/README.md">jQuery UI Widgets</a></div>
<a class="list-group-item" href="#navigation-338" data-toggle="collapse" data-parent="#navigation">Helpers <b class="caret"></b></a><div id="navigation-338" class="submenu panel-collapse collapse"><a class="list-group-item" href="./guide-helper-overview.html">Overview</a>
<a class="list-group-item" href="./guide-helper-array.html">ArrayHelper</a>
<a class="list-group-item" href="./guide-helper-html.html">Html</a>
<a class="list-group-item" href="./guide-helper-url.html">Url</a></div></div>    </div>
    <div class="col-md-9 guide-content" role="main">
        <h1>Configurations <span id="configurations"></span><a href="#configurations" class="hashlink">&para;</a></h1>
<div class="toc"><ol><li><a href="#configuration-format">Configuration Format</a></li>
<li><a href="#using-configurations">Using Configurations</a></li>
<li><a href="#configuration-files">Configuration Files</a></li>
<li><a href="#default-configurations">Default Configurations</a></li>
<li><a href="#environment-constants">Environment Constants</a></li></ol></div>
<p>Configurations are widely used in Yii when creating new objects or initializing existing objects.
Configurations usually include the class name of the object being created, and a list of initial values
that should be assigned to the object's <a href="guide-concept-properties.html">properties</a>. Configurations may also include a list of
handlers that should be attached to the object's <a href="guide-concept-events.html">events</a> and/or a list of
<a href="guide-concept-behaviors.html">behaviors</a> that should also be attached to the object.</p>
<p>In the following, a configuration is used to create and initialize a database connection:</p>
<pre><code class="hljs php language-php"><span class="hljs-variable">$config</span> = [
    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\db\Connection'</span>,
    <span class="hljs-string">'dsn'</span> =&gt; <span class="hljs-string">'mysql:host=127.0.0.1;dbname=demo'</span>,
    <span class="hljs-string">'username'</span> =&gt; <span class="hljs-string">'root'</span>,
    <span class="hljs-string">'password'</span> =&gt; <span class="hljs-string">''</span>,
    <span class="hljs-string">'charset'</span> =&gt; <span class="hljs-string">'utf8'</span>,
];

<span class="hljs-variable">$db</span> = Yii::createObject(<span class="hljs-variable">$config</span>);
</code></pre>
<p>The <a href="./yii-baseyii.html#createObject()-detail">Yii::createObject()</a> method takes a configuration array as its argument, and creates an object by instantiating
the class named in the configuration. When the object is instantiated, the rest of the configuration
will be used to initialize the object's properties, event handlers, and behaviors.</p>
<p>If you already have an object, you may use <a href="./yii-baseyii.html#configure()-detail">Yii::configure()</a> to initialize the object's properties with
a configuration array:</p>
<pre><code class="hljs php language-php">Yii::configure(<span class="hljs-variable">$object</span>, <span class="hljs-variable">$config</span>);
</code></pre>
<p>Note that, in this case, the configuration array should not contain a <code>class</code> element.</p>
<h2>Configuration Format  <span id="configuration-format"></span><a href="#configuration-format" class="hashlink">&para;</a></h2><p>The format of a configuration can be formally described as:</p>
<pre><code class="hljs php language-php">[
    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'ClassName'</span>,
    <span class="hljs-string">'propertyName'</span> =&gt; <span class="hljs-string">'propertyValue'</span>,
    <span class="hljs-string">'on eventName'</span> =&gt; <span class="hljs-variable">$eventHandler</span>,
    <span class="hljs-string">'as behaviorName'</span> =&gt; <span class="hljs-variable">$behaviorConfig</span>,
]
</code></pre>
<p>where</p>
<ul>
<li>The <code>class</code> element specifies a fully qualified class name for the object being created.</li>
<li>The <code>propertyName</code> elements specify the initial values for the named property. The keys are the property names, and the
values are the corresponding initial values. Only public member variables and <a href="guide-concept-properties.html">properties</a>
defined by getters/setters can be configured.</li>
<li>The <code>on eventName</code> elements specify what handlers should be attached to the object's <a href="guide-concept-events.html">events</a>.
Notice that the array keys are formed by prefixing event names with <code>on </code>. Please refer to
the <a href="guide-concept-events.html">Events</a> section for supported event handler formats.</li>
<li>The <code>as behaviorName</code> elements specify what <a href="guide-concept-behaviors.html">behaviors</a> should be attached to the object.
Notice that the array keys are formed by prefixing behavior names with <code>as </code>; the value, <code>$behaviorConfig</code>, represents
the configuration for creating a behavior, like a normal configuration  described here.</li>
</ul>
<p>Below is an example showing a configuration with initial property values, event handlers, and behaviors:</p>
<pre><code class="hljs php language-php">[
    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'app\components\SearchEngine'</span>,
    <span class="hljs-string">'apiKey'</span> =&gt; <span class="hljs-string">'xxxxxxxx'</span>,
    <span class="hljs-string">'on search'</span> =&gt; <span class="hljs-function"><span class="hljs-keyword">function</span> <span class="hljs-params">(<span class="hljs-variable">$event</span>)</span> </span>{
        Yii::info(<span class="hljs-string">"Keyword searched: "</span> . <span class="hljs-variable">$event</span>-&gt;keyword);
    },
    <span class="hljs-string">'as indexer'</span> =&gt; [
        <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'app\components\IndexerBehavior'</span>,
        <span class="hljs-comment">// ... property init values ...</span>
    ],
]
</code></pre>
<h2>Using Configurations  <span id="using-configurations"></span><a href="#using-configurations" class="hashlink">&para;</a></h2><p>Configurations are used in many places in Yii. At the beginning of this section, we have shown how to 
create an object according to a configuration by using <a href="./yii-baseyii.html#createObject()-detail">Yii::createObject()</a>. In this subsection, we will
describe application configurations and widget configurations - two major usages of configurations.</p>
<h3>Application Configurations  <span id="application-configurations"></span><a href="#application-configurations" class="hashlink">&para;</a></h3><p>The configuration for an <a href="guide-structure-applications.html">application</a> is probably one of the most complex arrays in Yii.
This is because the <a href="./yii-web-application.html">application</a> class has a lot of configurable properties and events.
More importantly, its <a href="./yii-di-servicelocator.html#$components-detail">components</a> property can receive an array of configurations
for creating components that are registered through the application. The following is an abstract from the application
configuration file for the <a href="guide-start-installation.html">Basic Project Template</a>.</p>
<pre><code class="hljs php language-php"><span class="hljs-variable">$config</span> = [
    <span class="hljs-string">'id'</span> =&gt; <span class="hljs-string">'basic'</span>,
    <span class="hljs-string">'basePath'</span> =&gt; dirname(<span class="hljs-keyword">__DIR__</span>),
    <span class="hljs-string">'extensions'</span> =&gt; <span class="hljs-keyword">require</span>(<span class="hljs-keyword">__DIR__</span> . <span class="hljs-string">'/../vendor/yiisoft/extensions.php'</span>),
    <span class="hljs-string">'components'</span> =&gt; [
        <span class="hljs-string">'cache'</span> =&gt; [
            <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\caching\FileCache'</span>,
        ],
        <span class="hljs-string">'mailer'</span> =&gt; [
            <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\swiftmailer\Mailer'</span>,
        ],
        <span class="hljs-string">'log'</span> =&gt; [
            <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\Dispatcher'</span>,
            <span class="hljs-string">'traceLevel'</span> =&gt; YII_DEBUG ? <span class="hljs-number">3</span> : <span class="hljs-number">0</span>,
            <span class="hljs-string">'targets'</span> =&gt; [
                [
                    <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\FileTarget'</span>,
                ],
            ],
        ],
        <span class="hljs-string">'db'</span> =&gt; [
            <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\db\Connection'</span>,
            <span class="hljs-string">'dsn'</span> =&gt; <span class="hljs-string">'mysql:host=localhost;dbname=stay2'</span>,
            <span class="hljs-string">'username'</span> =&gt; <span class="hljs-string">'root'</span>,
            <span class="hljs-string">'password'</span> =&gt; <span class="hljs-string">''</span>,
            <span class="hljs-string">'charset'</span> =&gt; <span class="hljs-string">'utf8'</span>,
        ],
    ],
];
</code></pre>
<p>The configuration does not have a <code>class</code> key. This is because it is used as follows in
an <a href="guide-structure-entry-scripts.html">entry script</a>, where the class name is already given,</p>
<pre><code class="hljs php language-php">(<span class="hljs-keyword">new</span> yii\web\Application(<span class="hljs-variable">$config</span>))-&gt;run();
</code></pre>
<p>More details about configuring the <code>components</code> property of an application can be found
in the <a href="guide-structure-applications.html">Applications</a> section and the <a href="guide-concept-service-locator.html">Service Locator</a> section.</p>
<h3>Widget Configurations  <span id="widget-configurations"></span><a href="#widget-configurations" class="hashlink">&para;</a></h3><p>When using <a href="guide-structure-widgets.html">widgets</a>, you often need to use configurations to customize the widget properties.
Both of the <a href="./yii-base-widget.html#widget()-detail">yii\base\Widget::widget()</a> and <a href="./yii-base-widget.html#begin()-detail">yii\base\Widget::begin()</a> methods can be used to create
a widget. They take a configuration array, like the following,</p>
<pre><code class="hljs php language-php"><span class="hljs-keyword">use</span> <span class="hljs-title">yii</span>\<span class="hljs-title">widgets</span>\<span class="hljs-title">Menu</span>;

<span class="hljs-keyword">echo</span> Menu::widget([
    <span class="hljs-string">'activateItems'</span> =&gt; <span class="hljs-keyword">false</span>,
    <span class="hljs-string">'items'</span> =&gt; [
        [<span class="hljs-string">'label'</span> =&gt; <span class="hljs-string">'Home'</span>, <span class="hljs-string">'url'</span> =&gt; [<span class="hljs-string">'site/index'</span>]],
        [<span class="hljs-string">'label'</span> =&gt; <span class="hljs-string">'Products'</span>, <span class="hljs-string">'url'</span> =&gt; [<span class="hljs-string">'product/index'</span>]],
        [<span class="hljs-string">'label'</span> =&gt; <span class="hljs-string">'Login'</span>, <span class="hljs-string">'url'</span> =&gt; [<span class="hljs-string">'site/login'</span>], <span class="hljs-string">'visible'</span> =&gt; Yii::<span class="hljs-variable">$app</span>-&gt;user-&gt;isGuest],
    ],
]);
</code></pre>
<p>The above code creates a <code>Menu</code> widget and initializes its <code>activateItems</code> property to be false.
The <code>items</code> property is also configured with menu items to be displayed.</p>
<p>Note that because the class name is already given, the configuration array should NOT have the <code>class</code> key.</p>
<h2>Configuration Files  <span id="configuration-files"></span><a href="#configuration-files" class="hashlink">&para;</a></h2><p>When a configuration is very complex, a common practice is to store it in one or multiple PHP files, known as
<em>configuration files</em>. A configuration file returns a PHP array representing the configuration.
For example, you may keep an application configuration in a file named <code>web.php</code>, like the following,</p>
<pre><code class="hljs php language-php"><span class="hljs-keyword">return</span> [
    <span class="hljs-string">'id'</span> =&gt; <span class="hljs-string">'basic'</span>,
    <span class="hljs-string">'basePath'</span> =&gt; dirname(<span class="hljs-keyword">__DIR__</span>),
    <span class="hljs-string">'extensions'</span> =&gt; <span class="hljs-keyword">require</span>(<span class="hljs-keyword">__DIR__</span> . <span class="hljs-string">'/../vendor/yiisoft/extensions.php'</span>),
    <span class="hljs-string">'components'</span> =&gt; <span class="hljs-keyword">require</span>(<span class="hljs-keyword">__DIR__</span> . <span class="hljs-string">'/components.php'</span>),
];
</code></pre>
<p>Because the <code>components</code> configuration is complex too, you store it in a separate file called <code>components.php</code>
and "require" this file in <code>web.php</code> as shown above. The content of <code>components.php</code> is as follows,</p>
<pre><code class="hljs php language-php"><span class="hljs-keyword">return</span> [
    <span class="hljs-string">'cache'</span> =&gt; [
        <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\caching\FileCache'</span>,
    ],
    <span class="hljs-string">'mailer'</span> =&gt; [
        <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\swiftmailer\Mailer'</span>,
    ],
    <span class="hljs-string">'log'</span> =&gt; [
        <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\Dispatcher'</span>,
        <span class="hljs-string">'traceLevel'</span> =&gt; YII_DEBUG ? <span class="hljs-number">3</span> : <span class="hljs-number">0</span>,
        <span class="hljs-string">'targets'</span> =&gt; [
            [
                <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\log\FileTarget'</span>,
            ],
        ],
    ],
    <span class="hljs-string">'db'</span> =&gt; [
        <span class="hljs-string">'class'</span> =&gt; <span class="hljs-string">'yii\db\Connection'</span>,
        <span class="hljs-string">'dsn'</span> =&gt; <span class="hljs-string">'mysql:host=localhost;dbname=stay2'</span>,
        <span class="hljs-string">'username'</span> =&gt; <span class="hljs-string">'root'</span>,
        <span class="hljs-string">'password'</span> =&gt; <span class="hljs-string">''</span>,
        <span class="hljs-string">'charset'</span> =&gt; <span class="hljs-string">'utf8'</span>,
    ],
];
</code></pre>
<p>To get a configuration stored in a configuration file, simply "require" it, like the following:</p>
<pre><code class="hljs php language-php"><span class="hljs-variable">$config</span> = <span class="hljs-keyword">require</span>(<span class="hljs-string">'path/to/web.php'</span>);
(<span class="hljs-keyword">new</span> yii\web\Application(<span class="hljs-variable">$config</span>))-&gt;run();
</code></pre>
<h2>Default Configurations  <span id="default-configurations"></span><a href="#default-configurations" class="hashlink">&para;</a></h2><p>The <a href="./yii-baseyii.html#createObject()-detail">Yii::createObject()</a> method is implemented based on a <a href="guide-concept-di-container.html">dependency injection container</a>.
It allows you to specify a set of the so-called <em>default configurations</em> which will be applied to ALL instances of
the specified classes when they are being created using <a href="./yii-baseyii.html#createObject()-detail">Yii::createObject()</a>. The default configurations
can be specified by calling <code>Yii::$container-&gt;set()</code> in the <a href="guide-runtime-bootstrapping.html">bootstrapping</a> code.</p>
<p>For example, if you want to customize <a href="./yii-widgets-linkpager.html">yii\widgets\LinkPager</a> so that ALL link pagers will show at most 5 page buttons
(the default value is 10), you may use the following code to achieve this goal,</p>
<pre><code class="hljs php language-php">\Yii::<span class="hljs-variable">$container</span>-&gt;set(<span class="hljs-string">'yii\widgets\LinkPager'</span>, [
    <span class="hljs-string">'maxButtonCount'</span> =&gt; <span class="hljs-number">5</span>,
]);
</code></pre>
<p>Without using default configurations, you would have to configure <code>maxButtonCount</code> in every place where you use
link pagers.</p>
<h2>Environment Constants  <span id="environment-constants"></span><a href="#environment-constants" class="hashlink">&para;</a></h2><p>Configurations often vary according to the environment in which an application runs. For example,
in development environment, you may want to use a database named <code>mydb_dev</code>, while on production server
you may want to use the <code>mydb_prod</code> database. To facilitate switching environments, Yii provides a constant
named <code>YII_ENV</code> that you may define in the <a href="guide-structure-entry-scripts.html">entry script</a> of your application.
For example,</p>
<pre><code class="hljs php language-php">defined(<span class="hljs-string">'YII_ENV'</span>) <span class="hljs-keyword">or</span> define(<span class="hljs-string">'YII_ENV'</span>, <span class="hljs-string">'dev'</span>);
</code></pre>
<p>You may define <code>YII_ENV</code> as one of the following values:</p>
<ul>
<li><code>prod</code>: production environment. The constant <code>YII_ENV_PROD</code> will evaluate as true.
This is the default value of <code>YII_ENV</code> if you do not define it.</li>
<li><code>dev</code>: development environment. The constant <code>YII_ENV_DEV</code> will evaluate as true.</li>
<li><code>test</code>: testing environment. The constant <code>YII_ENV_TEST</code> will evaluate as true.</li>
</ul>
<p>With these environment constants, you may specify your configurations conditionally based on
the current environment. For example, your application configuration may contain the following
code to enable the <a href="guide-tool-debugger.html">debug toolbar and debugger</a> in development environment.</p>
<pre><code class="hljs php language-php"><span class="hljs-variable">$config</span> = [...];

<span class="hljs-keyword">if</span> (YII_ENV_DEV) {
    <span class="hljs-comment">// configuration adjustments for 'dev' environment</span>
    <span class="hljs-variable">$config</span>[<span class="hljs-string">'bootstrap'</span>][] = <span class="hljs-string">'debug'</span>;
    <span class="hljs-variable">$config</span>[<span class="hljs-string">'modules'</span>][<span class="hljs-string">'debug'</span>] = <span class="hljs-string">'yii\debug\Module'</span>;
}

<span class="hljs-keyword">return</span> <span class="hljs-variable">$config</span>;
</code></pre>
        <div class="toplink"><a href="#" class="h1" title="go to top"><span class="glyphicon glyphicon-arrow-up"></a></div>
    </div>
</div>


</div>

<footer class="footer">
        <p class="pull-right"><small>Page generated on Sat, 09 Jul 2016 12:16:28 +0000</small></p>
    Powered by <a href="http://www.yiiframework.com/" rel="external">Yii Framework</a></footer>

<script type="text/javascript">jQuery(document).ready(function () {
    var shiftWindow = function () { scrollBy(0, -50) };
    if (location.hash) setTimeout(shiftWindow, 1);
    window.addEventListener("hashchange", shiftWindow);
var element = document.createElement("script");
element.src = "./jssearch.index.js";
document.body.appendChild(element);

var searchBox = $('#searchbox');

// search when typing in search field
searchBox.on("keyup", function(event) {
    var query = $(this).val();

    if (query == '' || event.which == 27) {
        $('#search-resultbox').hide();
        return;
    } else if (event.which == 13) {
        var selectedLink = $('#search-resultbox a.selected');
        if (selectedLink.length != 0) {
            document.location = selectedLink.attr('href');
            return;
        }
    } else if (event.which == 38 || event.which == 40) {
        $('#search-resultbox').show();

        var selected = $('#search-resultbox a.selected');
        if (selected.length == 0) {
            $('#search-results').find('a').first().addClass('selected');
        } else {
            var next;
            if (event.which == 40) {
                next = selected.parent().next().find('a').first();
            } else {
                next = selected.parent().prev().find('a').first();
            }
            if (next.length != 0) {
                var resultbox = $('#search-results');
                var position = next.position();

//              TODO scrolling is buggy and jumps around
//                resultbox.scrollTop(Math.floor(position.top));
//                console.log(position.top);

                selected.removeClass('selected');
                next.addClass('selected');
            }
        }

        return;
    }
    $('#search-resultbox').show();
    $('#search-results').html('<li><span class="no-results">No results</span></li>');

    var result = jssearch.search(query);

    if (result.length > 0) {
        var i = 0;
        var resHtml = '';

        for (var key in result) {
            if (i++ > 20) {
                break;
            }
            resHtml = resHtml +
            '<li><a href="' + result[key].file.u.substr(3) +'"><span class="title">' + result[key].file.t + '</span>' +
            '<span class="description">' + result[key].file.d + '</span></a></li>';
        }
        $('#search-results').html(resHtml);
    }
});

// hide the search results on ESC
$(document).on("keyup", function(event) { if (event.which == 27) { $('#search-resultbox').hide(); } });
// hide search results on click to document
$(document).bind('click', function (e) { $('#search-resultbox').hide(); });
// except the following:
searchBox.bind('click', function(e) { e.stopPropagation(); });
$('#search-resultbox').bind('click', function(e) { e.stopPropagation(); });

});</script></body>
</html>
